Loading...
 

Directed Graph (WebWidget)

Directed Graph (WebWidget)

A directed graph (also called digraph) consists of a set of nodes and a set of directed edges. The edges are directed in the sense that they point in a unique direction. If V is the set of all vertices, then an edge is identified by the ordered pair (v, w), where v and w are from V.

A loop is an edge that connects a knot to itself (v, v). Multiple edges (called multi edges or parallel edges) are the edges that connect the same pair of nodes with each other. Of course, multiple edges can no longer be clearly identified by a pair of vertices, so the edges should be distinguishable by a text if the clear identification of the edges is of interest. In this case an edge is identified by (v, w, text).

In this web widget, the general graph that allows loops and multiple edges is assumed to be the standard graph, so a loopless single edge graph is called a simple or plain digraph. If one were to assume the simple digraph as the standard graph, one would be able to say This WebWidget also supports multigraphs.

Example of a directed graph
Example of a directed graph

Use

Web(digraph, APP("directedGraph.html"), 0, 0, 800, 600)

Dependencies

  • directedGraph.html
  • directedGraph-directive.js
  • dependencies/directedGraph-style.css
  • dependencies/d3.min.js
  • dependencies/dagre-d3.min.js

Message interface

When describing the direction, the WebWidget is divided into its two components. The WebWidget implemented in HTML, which implements the presentation logic and user interaction in the browser and the WebWidget implemented in InstantView, which supplies the other side with the data from ClassiX and controls it.

Name Parameters Description
Push News (IV→HTML)
data Data This message passes a data object to the Web widget as CX_JSON_OBJECT and contains all required data, styles and options about the graph to be displayed or about only individual nodes and edges. This message can be sent as often as required. Depending on the content of the message (see option redraw), this message can have a supplementary or overwriting effect.
expand String|JSON

This control message can be used to expand certain nodes, all visible nodes or all nodes of the graph.

The following can be specified as parameters:

  • "ALL": unfolds all nodes. If there are unloaded nodes, they are fetched and expanded by the message FETCH_ALL.
  • "ALL_VISIBLE": expands all loaded nodes. Source nodes with unloaded predecessors or sink nodes with unloaded successors only ask for their immediate predecessors or successors using FETCH_PREDECESSORS or FETCH_SUCCESSORS.
  • The ID of the node: If only a single node should be expanded in both directions, then it is sufficient to specify its ID.
  • A CX_JSON_ARRAY with the IDs of several nodes: Same as in the previous case, but for multiple nodes at once.
  • A CX_JSON_OBJECT of the form {preButton: X, sucButton: Y}: Here you can specify whether certain nodes should only be expanded at the predecessor button or only at the successor button. The object can also consist only of preButton or sucButton. X and Y can be an ID or an array of IDs.
collapse String|JSON

This control message can be used to collapse certain nodes, all visible nodes or all nodes of the graph.

The parameter constellation is similar to that of the message expand.

Events (HTML→IV)
INITIALIZE_SOCKET - The first message that the WebWidget sends once it has initialised. This indicates that the WebWidget is ready to receive and process push messages.
MOUSE_CLICK_SOCKET JSON string

Is fired when the user clicks on a node or edge.

parameters: JSON string with the attributes:

In case of a clicked node:

  • the ID of the clicked node, if a node was clicked.

In case of a clicked edge:

  • from: the ID of the node from which the edge originates
  • to: the ID of the node into which the edge goes
  • text: the text of the edge, if available
DOUBLE_CLICK_SOCKET JSON string

Is fired when the user double-clicks on a node or edge.

The parameters of the JSON string are identical to those of the MOUSE_CLICK_SOCKET event.

FETCH_PREDECESSORS_SOCKET String

Is fired when the user opens a node on the previous button. ClassiX only has to respond with a data message if the status of the predecessor has been updated in the meantime or has not yet been communicated to the web widget. Otherwise the opening process is carried out with the predecessors known to the WebWidget anyway.

The ID of the expanded node is passed as a parameter.

FETCH_SUCCESSORS_SOCKET String

Is fired when the user opens a node on the successor button. ClassiX only has to reply with a data message if the status of the successors has been updated in the meantime or has not yet been communicated to the WebWidget. Otherwise the opening process is performed with the successors known to the WebWidget anyway.

The ID of the expanded node is passed as a parameter.

FETCH_ALL_SOCKET - Will be fired if the WebWidget has to expand all nodes but does not have the necessary data about all nodes and edges. In response, the WebWidget expects a data message in which all source nodes are ancestorless (hasParents: false) and all sink nodes are successorless (hasChildren: false).

The Data Object

The data object is of type CX_JSON_OBJECT and transfers the nodes, edges, styles and/or options for the display. A data object can contain overwriting, correcting, supplementing or deleting data. There are no mandatory fields.

Field Type Description
nodes ARRAY(Node) An array of node objects that represent the nodes in the graph.
edges ARRAY(Edge) An array of edge objects that represent the edges in the graph.
styles StylesObject A CX_JSON_OBJECT that contains the style objects as members So the name and the identifier of a style object is not contained in the style object itself, but as a member name of the whole style object.
options Option object A CX_JSON_OBJECT that contains all graph display options.

The Node Object

The node object is of type CX_JSON_OBJECT and represents a node in the digraph. Highlighted fields are mandatory.

Field Type Default value Description
id String - The unique ID of the node
text String - The text of a node. Multiple lines can be specified with the character \n.
icon String - If desired, the path to an icon from the ClassiX Icons.
tooltipTitle String - If desired the node gets a tooltip with a title (single line).
tooltip text String - If you want more information to be displayed as detailed text in the tooltip, you could use this option.
hasSuccessors Boolean FALSE This specification is only relevant for sink nodes, so that the graph knows about the existence of unloaded but existing successors and displays a successor button accordingly.
hasPredecessors Boolean FALSE This specification is only relevant for source nodes, so that the graph knows about the existence of unloaded but existing predecessors and displays a predecessor button accordingly.
style String | Style object s. Style objects The name of the style to be applied or directly an individual style object.
hoverStyle String | Style object s. Style objects The name of the style to apply when hovering this node.
predecessors String | Array (String | Edge) -

The ID or IDs of one or more predecessors or the same as the predecessor edges as edge objects. Mixed arrays are possible.

Alternatively, the relations between the nodes under edges could be defined conventionally.

successors String | Array (String | Edge) -

The ID or IDs of one or more successors or the same the successor edges as edge objects. Mixed arrays are possible.

Alternatively, the relations between the nodes under edges could be defined conventionally.

delete Boolean FALSE If the node should be deleted, this field is set to TRUE. The identification is made by the field id.

Note: Nodes sent with the first message or with an overwriting message are called primary nodes and do not disappear when their edges are collapsed.

The Edge Object

The Edge object is of type CX_JSON_OBJECT and represents an edge in the digraph. Highlighted fields are mandatory.

Field Type Default value Description
from String - The ID of the node from which this edge originates.
to String - The ID of the node into which this edge goes.
text String - The inscription of the edge, if inscription is desired. However, this field is also used to identify the edge in multigraphs and could be practically mandatory in certain cases. See the introduction to this article.
newText String - If the text of an edge should be updated, the new text must be entered under newText, because the field text is used to identify the edge.
style String | Style object s. Style objects The name of the style to be applied or directly an individual style object.
hoverStyle String | Style object s. Style objects The name of the style to apply when hovering this edge.
tooltipTitle String - If desired the node gets a tooltip with a title (single line).
tooltip text String - If you want more information to be displayed as detailed text in the tooltip, you could use this option.
delete Boolean FALSE If the edge should be deleted, this field is set to TRUE. The identification is done with the fields from, to and text. If text is omitted, all edges between the two nodes are deleted.
Relevant only in case of use in connection with the options successors and predecessors of nodes
id String - The ID of the predecessor or successor that this edge connects to the node containing its definition. In this case, the from and to specifications are not allowed because they are redundant.

The style object

The style object is a CX_JSON_OBJECT and contains several properties for adjusting the display of nodes and edges. The sense of a style object is that it can be used for several nodes and edges without having to define it redundantly in several places.

Property Type When hovering Default value Description
Style properties for nodes
shape String Not changeable rect The shape of a knot. The following shapes are supported: rect, ellipse, circle, diamond
rx Integer Not changeable 5 The horizontal radius of curvature in pixels at the corner of a rectangle. Only applicable with rect.
ry Integer Not changeable 5 The vertical radius of curvature in pixels at the corner of a rectangle. Only applicable with rect.
paddingLeft Integer Not changeable 10 The additional inner left distance of a node in pixels.
paddingRight Integer Not changeable 10 The additional right inner distance of a node in pixels.
paddingTop Integer Not changeable 10 The additional upper inner distance of a node in pixels.
paddingBottom Integer Not changeable 10 The additional lower inner distance of a node in pixels.
predecessorsCollapsible Boolean Not changeable TRUE

Disables the ability for the user to expand or collapse a node on the previous button. The node can then only be expanded and collapsed programmatically using the predecessorsCollapsed property or the control messages expand and collapse.

Source nodes with unloaded predecessors are an exception and do not obey this rule.

successorsCollapsible Boolean Not changeable TRUE

Disables the ability for the user to expand or collapse a node on the successor button. The node can then only be expanded and collapsed programmatically using the property successorsCollapsed or the control messages expand and collapse.

Countersunk nodes with unloaded successors are an exception and do not obey this rule.

predecessorsCollapsed Boolean Not changeable FALSE If set, the node at the previous button is collapsed, otherwise it is expanded.
successorsCollapsed Boolean Not changeable FALSE If set, the node at the successor button is collapsed, otherwise it is expanded.
borderColor String Changeable #999 Border colour of the node in HTML colour string format.
borderWidth Integer Changeable 1 Border width of the node in pixels.
bgColor String Changeable #fff Background colour of the node in HTML colour string format.
textColor String Changeable #000 Text colour of the node in HTML colour string format.
cursor String Changeable car Determines the display of the mouse cursor when it hovers over the node. The possible values can be found in the normal CSS rules. Often 'pointers' are used to display a hand.
Style properties for edges
arrowhead String Not changeable vee Defines the display form of the edge tip. Possible values are: vee, normal and undirected. Undirected transforms the graph only externally into an undirected graph.
curveType String Not changeable basis The interpolation method of the edges between the nodes. Possible values are: linear, step, stepBefore, stepAfter, basis, cardinal, monotoneX, carmullRom
textColor String Changeable #999 Text colour of the edge in HTML colour string format.
lineColor String Changeable #999 Edge colour in HTML colour string format.
lineWidth Integer Changeable 2 Edge width in pixels.
cursor String Changeable car Determines the appearance of the mouse cursor when it hovers over the edge. The possible values can be found in the normal CSS rules.
zIndex Integer Not changeable 0 Edge styles with a higher zIndex value will have their edges over those with an edge style with a lower zIndex value. This is usually used to determine which edge colour should be displayed when two differently coloured edges overlap.

The Option Object

The Options object is of type CX_JSON_OBJECT and contains various general settings for adjusting the graph as a whole. No setting is mandatory.

Field Type Default value Description
direction String TB

Specifies the orientation of the graph. Possible values are:

  • TB: from top to bottom
  • BT: from bottom to top
  • RL: from right to left
  • LR: from left to right
edgeSpacing Integer 10 Defines the minimum distance between the edges in pixels
nodeSpacing Integer 10 Defines the minimum distance between the nodes in pixels
levelSpacing Integer 60 Defines the minimum distance between the node levels (predecessor and successor) in pixels.
horizontalLabels Boolean FALSE By default, an attempt is made to ensure that the lettering on an edge follows its course if the edge is long enough, otherwise the lettering is aligned horizontally. With this option, you can always set the orientation of the label horizontally, regardless of the course or length of an edge.
arrowSpacing Integer 35 If several edges lead in or out of a node, they are combined into a single point and their arrowheads merge into a single common arrowhead. The distance between the arrowhead and the merge point is defined by this option. For outgoing edges, this option determines the length of the vertical lines, as there are no arrowheads.
defaultNodeStyle Style object s. Style object With this option you can set a default value for the style of all nodes that do not have their own style.
defaultNodeHoverStyle Style object - This option allows you to set a default value for the style to be applied to the mouse hover of all nodes that do not have their own hover style.
defaultEdgeStyle Style object s. Style object With this option you can set a default value for the style of all edges that do not have their own style.
defaultEdgeHoverStyle Style object - With this option you can set a default value for the style to be applied when mouse hovering for all nodes that do not have their own hover style.
redraw Boolean FALSE If set, all existing nodes and edges in the graph are discarded and overwritten with the new ones. Otherwise, each data message has a complementary effect to enable successive graph formation.